ドキュメントの文法(シンタックス)【CCG執筆者向け】
はじめに
本ブログは ナレッジサイトである Classmethod Cloud Guidebook(CCG) [1] の執筆者向けに公開しているブログです。 一般的なMarkdown(MkDocs)シンタックスでも参考になる部分があると思うので、ブログにて公開しています。
CCGを構成しているドキュメントの文法(シンタックス)を共有します。 執筆の際のリファレンスとして活用してください。
基本の Markdownシンタックス
CCGは 静的サイトジェネレーターである MkDocs (およびその拡張プラグインである Material for MkDocs )から構成されています。 MkDocsでは Markdown で記載されたドキュメントを表示します。
基本的なMarkdown記法については、 普段のブログ執筆などで慣れていると思うので 丁寧に説明しません。
以降で「人によって差異が出やすいポイント」に絞って紹介します。
見出し
見出しはレベル2以降を使います。
見出しレベル1はドキュメントタイトルです。
# ドキュメントタイトル
## 見出しレベル2
見出しレベル2以降を使って、文章を構成ください。
### 見出しレベル3
#### 見出しレベル4
見た目
段落、改行
段落を作る場合は、空白行を追加してください。
1改行のみの場合は、表示上は改行されません。
空白行を入れて段落を作成。
1改行のみだと、
表示場は改行されない。
見た目
リスト
リストの前後には空白行を入れてください。
また、ネストする場合は「半角スペース 4つ」を空けてください。
リストの前後には空白行。ネストはスペース4つ。
- アイテム1
- アイテム1.1
- アイテム1.2
- アイテム2
見た目
画像
 の形式で画像を挿入します。 イメージパスはリポジトリ内にある画像の場合、相対パスで記載します。
クラスメソッドメンバーズのロゴ
見た目
リンク
[タイトル](URL) 形式で書きます。 タイトルには出典元を載せましょう。
[クラスメソッド発「やってみた」系技術メディア | DevelopersIO](https://dev.classmethod.jp/)
見た目
コメントアウト
<!-- および --> で括られた部分はコメントアウトとなります。
コメントアウトした情報も、MkDocsのビルドに含まれることに注意してください。
機微な情報は載せないようにしましょう。
おはよう。
<!-- TODO: こんにちわ。 -->
こんばんわ。
見た目
MkDocs(Material)独自のシンタックス
コールアウト
admonitions(call-outs) を使えます。 目立たせたい情報がある場合に役立ちます。
!!! note "コールアウトの使い方"
`!!!` から始まるブロックを書くことで、コールアウトを使えます。
<br> `note` 以外にも `abstract` や `info` など、様々なタイプがあります。
見た目
詳しい使い方は以下ページを参考ください。
Mermaid描画
Mermaid による図の描画が可能です。 フローチャートなどを書く際に便利です。
\```mermaid
graph TD
start([スタート]) --> topic[ネタを収集する]
topic --> blog[ブログを書く]
blog --> start
\```
見た目
詳しい使い方は以下ページを参考ください。 もしくは Mermaid リファレンス を参照ください。
アイコン、絵文字
アイコンや絵文字を挿入できます。
:motorcycle: :dash:
見た目
使える絵文字は以下ページで検索できます。
そのほか
他にも、Material for MkDocs に特化した記法があります。 使いたい場合は以下リファレンスを参照ください。
おわりに
以上、CCGドキュメントの文法(シンタックス)を共有しました。
ガンガン執筆していきましょう！
参考
